28.3.3 Size and Position

You can read or change the position of a frame using the frame parameters left and top (see Position Parameters) and its size using the height and width parameters (see Size Parameters). Here are some special features for working with sizes and positions. For all of these functions the argument frame must denote a live frame and defaults to the selected frame.

Function: frame-position &optional Lisp_Object &optional frame

This function returns the outer position (see Frame Layout) of frame in pixels. The value is a cons giving the coordinates of the top left corner of the outer frame of frame relative to an origin at the position (0, 0) of the frame’s display. On a text terminal frame both values are zero.

Function: set-frame-position frame X Y

This function sets the outer frame position of frame to X and Y. The latter arguments specify pixels and normally count from an origin at the position (0, 0) of frame’s display.

A negative parameter value positions the right edge of the outer frame by -x pixels left from the right edge of the screen or the bottom edge by -y pixels up from the bottom edge of the screen.

This function has no effect on text terminal frames.

Function: frame-pixel-height &optional frame

Function: frame-pixel-width &optional frame

These functions return the inner height and width (the height and width of the display area, see Frame Layout) of frame in pixels. For a text terminal, the results are in characters rather than pixels.

Function: frame-text-height &optional frame

Function: frame-text-width &optional frame

These functions return the height and width of the text area of frame (see Frame Layout), measured in pixels. For a text terminal, the results are in characters rather than pixels.

The value returned by frame-text-height differs from that returned by frame-pixel-height by not including the heights of any internal tool bar or menu bar, the height of one horizontal scroll bar and the widths of the internal border.

The value returned by frame-text-width differs from that returned by frame-pixel-width by not including the width of one vertical scroll bar, the widths of one left and one right fringe and the widths of the internal border.

Function: frame-height &optional frame

Function: frame-width &optional frame

These functions return the height and width of the text area of frame, measured in units of the default font height and width of frame (see Frame Font). These functions are plain shorthands for writing (frame-parameter frame 'height) and (frame-parameter frame 'width).

If the text area of frame measured in pixels is not a multiple of its default font size, the values returned by these functions are rounded down to the number of characters of the default font that fully fit into the text area.

User Option: frame-resize-pixelwise

If this option is nil, a frame’s size is usually rounded to a multiple of the current values of that frame’s frame-char-height and frame-char-width whenever the frame is resized. If this is non-nil, no rounding occurs, hence frame sizes can increase/decrease by one pixel.

Setting this variable usually causes the next resize operation to pass the corresponding size hints to the window manager. This means that this variable should be set only in a user’s initial file; applications should never bind it temporarily.

The precise meaning of a value of nil for this option depends on the toolkit used. Dragging the external border with the mouse is done character-wise provided the window manager is willing to process the corresponding size hints. Calling set-frame-size (see below) with arguments that do not specify the frame size as an integer multiple of its character size, however, may: be ignored, cause a rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-nil in order to make a frame appear truly maximized or full-screen.

Function: set-frame-size frame width height &optional pixelwise

This function sets the size of the text area of frame, measured in terms of the canonical height and width of a character on frame (see Frame Font).

The optional argument pixelwise non-nil means to measure the new width and height in units of pixels instead. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame size to a multiple of its character size.

Function: set-frame-height frame height &optional pretend pixelwise

This function resizes the text area of frame to a height of height lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays height lines of output in frame, but does not change its value for the actual height of the frame. This is only useful on text terminals. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height directly does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on text terminals.

The optional fourth argument pixelwise non-nil means that frame should be height pixels high. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame height to a multiple of its character height.

Function: set-frame-width frame width &optional pretend pixelwise

This function sets the width of the text area of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The optional fourth argument pixelwise non-nil means that frame should be width pixels wide. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to fully honor the request if it does not increase/decrease the frame width to a multiple of its character width.

None of these three functions will make a frame smaller than needed to display all of its windows together with their scroll bars, fringes, margins, dividers, mode and header lines. This contrasts with requests by the window manager triggered, for example, by dragging the external border of a frame with the mouse. Such requests are always honored by clipping, if necessary, portions that cannot be displayed at the right, bottom corner of the frame.